Using Variables (and Functions)

 

Note: This help file is the most complex one of the bunch.  This is because using variables is an extremely powerful thing.  While it may seem intimidating at first, it's very easy once you get the hang of it.  Print the page out and read it at your leisure, paying special attention to the examples.  After a small bit of practice, you will be making complex events and using variables to do things you never thought possible before.

 

Portal© variables give you more functionality over your mudding experience than just about any other feature.  When used in combination with other features such as aliases, macros, events, etc, the possibilities are endless.  This files has five major sections: variables overview, the set function, the if command, the system command and then a section of examples for each.

 

Using variables in text and commands is performed by simply adding the @ symbol before the variable, such as @aaa.  If the text option for that command (program options screen) is checked for the Var column, the variable will be replaced by the value.  For example, if @aaa=5, the command "say @aaa" would result in "say 5" instead.

 

Note: To use the literal name of the variable in a line, simply add another @ before the normal @.  So in the above example, "say @@aaa" would result in "say @aaa" instead.  This is useful when you want variables to change as a result of an if statement for example.  Using three @ symbols will evaluate the variable and put the @ symbol before the result.  So, if @aaa=50, "say @@@aaa" would result in "say @50" instead.

 

Variables come in two distinct kinds: User-Defined and System-Resident.

 

Variables Overview

 

User-Defined Variables

These are declared in the variables screen.  These variables can be named as the user desires (with some limitations) and can be created and deleted on request.

 

System-Resident Variables

These variables work exactly like User-Defined Variables, but are permanently assigned to the system and cannot be deleted.  They are designed for use as a kind of “instant buffer” when used with events and event commands as they do not need to be declared.

 

Portal© System-Resident Variables: @AA, @BB, @CC, @DD, @EE, @FF

 

System Variables

These variables are used for things in Portal© such as the HPBars and gauges and stuff.  When you assign a value to any system variable, the program automatically processes the tasks assigned to that variable.  For example, if you assign a value to the @HP variable, the HP gauge will be updated accordingly and any appropriate status events will be fired off etc.  Each of these variables are query-able as they are set-able.

 

Portal© System Variables

@HP                Hit points

@MAXHP         Hit point maximum

@SP                Spell points

@MAXSP         Spell point maximum

@GP1              Guild points 1

@MAXGP1       Guild point 1 maximum

@GP2              Guild points 2

@MAXGP2       Guild point 2 maximum

@ENEMY          Enemy health %

@ENAME          Enemy name (used with the Imagery)

@GLINE1         Displays <string> in Guild line 1 (left side of HP3 Bar)

@GLINE2         Displays <string> in Guild line 2 (right side of HP3 Bar)

@CAPTION      Changes/references the caption of the main screen

 

Note: The @GLINE1 and @GLINE2 values are saved literally.  That is, the color codes are saved as raw text.  So, if the left side of the HP3 bar had the word “Danger” in red, the value currently contained in @GLINE1 would be <rDanger>.  See the Appendix at the end of this file for more information on coloring the glines.

 

The ;process Command and the Set() Function

 

Processing variables are done in two basic ways; the ;process command and the set() function.  

 

The ;process command allows you access to many math and string manipulation functions as described below.  It consists of three parts, the Operand, the Operator and the Expression, with no spaces between the three components.

 

;process <Operand><Operator><Expression>

 

Note: You can use ";compile" in place of ";process" if you desire.

 

The set() function is almost identical to the ;process command, except for two distinct differences:

set(<Operand><Operator><Expression>)

 

Think of the differences between the two formats this way.  If you want to just set a variables value in a "behind the scenes" kind of way without returning or displaying anything, you would use the ;process command.  If, however, you wanted to not only change a variable's value, but then immediately use it in a calculation you are designing, then you would use the set() function.  Experience in using the two formats will quickly guide you in knowing which one to use at which time.

 

One aspect of variables is that variables are stings or integers, depending on how you use them.  If you process a string or a integer as a string, it will act as a string.  If you process an integer or a string as an integer, it will treat integers normally and strings as 0.  When dividing, any zeros are changed to 1 (to prevent division by 0) and any remainders are truncated.

 

The Operand

The operand is the left side of the "equation" in a process.  This is the variable or evaluator that receives the value of the process.  The operand must have the @ symbol in front.  A simple example of operand usage of the variable "blah" is ;process @blah=4.  This assigns 4 to the variable blah.

 

The Operand can be a variable or an evaluator.  Variables (either user-defined or system-resident) can be can be used on the left side of the operator, as part of the expression or both.  System Evaluators can only be used on the left side of the operator.  They cannot be used as part of the expression.  System References are the opposite, they can only be used as part of the expression, not the operand (think: read-only).

 

Portal© System Evaluators

@SOUND=<filename>

      Plays the .wav file located in ...\Portal\media\sounds\<filename>.wav.

If you wish, you can use the full path to the .wav file.

 

@MUSIC=<filename>~<repeat>

      Plays the music file located in ...\Portal\media\sounds\<filename>

The file can be any MIDI supported format (*.MID, *.RMI, etc.) or *.MP3 file.

If you include a <repeat> value of “true” the music file will automatically repeat when it finishes its cycle. This value is optional.

 

@IMAGE=<filename>~<label>

      Displays the .BMP (bitmap) file located in ...\Portal\media\images\<string>.BMP.

If no .BMP file exists, it will then try and load look for a .GIF file of the same name (...\Portal\media\images\<string>.GIF). The <label> will appear on the Imagery label. This value is optional.

 

@AVI=<filename>~<label>

Displays the .AVI (movie) file located in ...\Portal\media\images\<filename>.AVI. 

The <label> will appear on the Imagery label. This value is optional.

 

@TELL=<is it from me?>~<other person>~<message>

      Adds to the Tell Monitor.  All values are required, separated by ~.

      <from me?>         Whether the tell is to me (nothing) or from me (x)

      <other person>     Name of the other person the tell is to/from

      <message>           The message text

 

      Ex: Tell from me to Bob: x~Bob~Hey Bob!

      Ex: Tell from Bob to me: ~Bob~Bob: Hi!  How's it going?

 

To setup to have tells routed to the tell monitor, basically, set up an event "* tells you: *" to parse to variables @AA and @BB.  Then, for the action, setup ";process @TELL=~@AA~@BB"  It's that simple.

 

@CHAT=<command>~<chat line>~<who chatted>~<message>

      Adds to the Chat Monitor.  All values are required, separated by ~.

      <command>         Command to invoke the chat line (talk, chat, speak, etc.)

      <chat line>           Title of the chat line (must be unique)

      <who chatted>     Name of the person who chatted

      <message>           The message text

 

      Ex: gtalk~Guild Line~Bob~Hey guild!  How's it going?

 

@MWCOMBAT=<string>

      Combat event message window (HP4 Bar)

 

@MWGUILD=<string>

      Guild event message window (HP4 Bar)

 

@AUTOTYPER=<string>

      Appends <string> to the currently open Autotyper file.  (opens one if necessary)

      You can include the format #|<string> as well to specify a particular Autotyper file.  For example, “;process @AUTOTYPER=3|Blah” will append “Blah” to the 3rd Autotyper file.

 

@SYSTEM=<string>

      Appends <string> as a new system message displayed in the System Messages screen

 

@EXECUTE=<string>

      Attempts to (externally to Portal©) execute the filename <string>

 

System References

@TICKER

Returns the current ticker value.

@TIME

Returns the current time value.

@DATE

Returns the current date value.

@CHARTING

Returns 1 if charting, 0 if not charting.

@FOLLOWING

Returns 1 if following, 0 if not following.

@ROOM

Returns the current value of the room string (which appears in the status bar of Portal enhanced MUDs)

 

The Operator

The operator is the middle of a process command.  Most often, the operator is a = symbol.  The operator tells the program how you are going to assign the expression to the operand.  The different operators are described below.

 

=       Assigns expression to operand

+=     Adds expression to operand, then assigns the result to operand

-=      Subtracts expression from operand, then assigns the result to operand

*=      Multiplies expression and operand, then assigns the result to operand

/=      Divides operand by expression, then assigns the result to operand

++     Increments operand by 1, then assigns the result to operand

--       Decrements operand by 1, then assigns the result to operand

 

The Expression

Expressions can be direct values or one of the many functions provided below.  Direct values or functions can contain variables, but the variables must be prefixed by the @ symbol to identify them as variables and not just text.  Before the expression is assigned to the operand, all variables will be replaced by their current values.

 

You can use as many functions per process command as you desire, compounding them as you like, but spaces are not allowed (they will be considered part of a string).  For example, you can ;process @blah=cap(dl(abcd)) and end up with the variable blah assigned with Bcd.

 

Note: Functions can be used in any command as well (assuming you have the f(x) option in that command’s Program Options – Text Option checked).  This will allow you to operate on values and variables on the fly.

 

The functions available for use in expressions are listed below.

 

Numeric Functions

math(integer1+integer2)

      Adds integer1 and integer2, then returns the result

      Ex: math(4+2) returns 6

      Ex: math(4+@ccc) when ccc=50 returns 54

math(integer1-integer2)

      Subtracts integer2 from integer1, then returns the result

      Ex: math(4-2) returns 2

      Ex: math(4-@ccc) when ccc=50 returns -46

math(integer1*integer2)

      Multiplies integer1 and integer2, then returns the result

      Ex: math(4*2) returns 8

      Ex: math(4*@ccc) when ccc=50 returns 200

math(integer1/integer2)

      Divides integer1 by integer2, then returns the result (truncating any remainder)

      Ex: math(4/2) returns 2

      Ex: math(4/@ccc) when ccc=50 returns 0

      Ex: math(10/4) returns 2

math(integer1%integer2)

      Returns the modulus (remainder), if any, after dividing integer1 by integer2

      Ex: math(4%2) returns 0

      Ex: math(10%4) returns 2

math(integer1^Integer2)

      Raises integer1 to the integer2 power, then returns the result

      Ex: math(3^2) returns 9

      Ex: math(4^3) returns 64

sqrt(integer)

      Returns the square root of integer (truncating any remainder)

      Ex: sqrt(36) returns 6

      Ex: sqrt(18) returns 4

random(integer)

      Returns a random integer from 0 to integer-1

      Ex: random(50) returns a random value from 0-49

abs(integer)

      Returns the absolute value of any integer

      Ex: abs(-44) returns 44

sum(integer1,integer2,..,integerN)

      Returns the sum of all integers

      Ex: sum(10,20,30) returns 60

avg(integer1,integer2,..,integerN)

      Returns the average of all integers

      Ex: avg(10,20,30) returns 20

 

String Functions

cap(string)

      Capitalizes the first letter of string

      Ex: cap(fish) returns Fish

      Ex: cap(@aaa) when aaa=test returns Test

      Ex: cap(fish@bbb) when bbb=head returns Fishhead

CAP(string)

      Capitalizes every letter in string

      Ex: CAP(fish) returns FISH

      Ex: CAP(@aaa) when aaa=test returns TEST

      Ex: CAP(fish@bbb) when bbb=head returns FISHHEAD

lc(string)

      Forces every letter in string to lower-case

      Ex: lc(FISH) returns fish

      Ex: lc(@aaa) when aaa=TEST returns test

      Ex: lc(FiSh@bbb) when bbb=HeAd returns fishhead

dl(string)

      Deletes the leading character of string

      Ex: dl(jump) returns ump

dt(string)

      Deletes the trailing character of string

      Ex: dt(jump) returns jum

cls(string)

      Clears all leading spaces from string

      Ex: cls(             jump) returns jump

cts(string)

      Clears all trailing spaces from string

      Ex: cts(jump             ) returns jump

cbs(string)

      Clears both leading and trailing spaces from string

      Ex: cbs(             jump             ) returns jump

length(string)

      Returns the length of string (number of characters

      Ex: length(hey there) returns 9

pos(substring,string)

      Returns the position of substring within string

      If substring is not anywhere within string, pos returns 0

      Ex: pos(f,abcdefghi) returns 6

      Ex: pos(uck,I suck) returns 4

      Ex: pos(duck,I suck) returns 0

copy(string,start#,amount)

      Returns the portion of string starting with the start# character, amount characters long

      Ex: copy(abcdefg,2,3) returns bcd

      Ex: copy(abcdefg,1,4) returns abcd

      Ex: copy(abcdefg,2,99999) returns bcdefg

delete(string,start#,amount)

      Deletes amount characters starting with start# from string

      Ex delete(abcdefg,2,3) returns aefg

      Ex delete(abcdefg,1,4) returns efg

      Ex delete(abcdefg,2,99999) returns a

subs(stringtoreplace,newstring,string)

      Substitutes all instances of stringtoreplace in string with newstring

      Ex: subs(x,a,xyz) returns ayz

      Ex: subs( ,,a b      c   d  e f) returns abcdef

      Ex: subs(a,1,@test) when test=aardvark returns 11rdv1rk

 

Note: Sometimes you might like to actually use the comma character when manipulating strings using the string functions.  Using the comma alone won’t work (as it’s used to separate the different parts of functions), so Portal© provides you with the literal comma character “\,” (backslash followed immediately by a comma).  Use the literal comma wherever you want to end up with a regular comma.  While the “literal comma character” is really two characters, it’s considered functionally to be only one character.  This is important to remember when using functions like pos(), copy() or delete(), as the exact location of a character is vital to these function.

 

pos(substring,string) (using the literal comma character)

      Returns the position of substring within string

      If substring is not anywhere within string, pos returns 0

      Ex: pos(f,abc\,defghi) returns 7

      Ex: pos(\,,I\, suck) returns 2

      Ex: pos(duck\,,I suck) returns 0

 

copy(string,start#,amount) (using the literal comma character)

      Returns the portion of string starting with the start# character, amount characters long

      Ex: copy(ab\,cdefg,2,3) returns b,c

      Ex: copy(\,abcdefg,1,4) returns ,abc

      Ex: copy(abcdef\,g,2,99999) returns bcdef,g

 

delete(string,start#,amount) (using the literal comma character)

      Deletes amount characters starting with start# from string

      Ex delete(ab\,cdefg,2,3) returns adefg

      Ex delete(\,abcdefg,1,4) returns defg

      Ex delete(\,abcdefg,2,99999) returns ,

 

subs(stringtoreplace,newstring,string) (using the literal comma character)

      Substitutes all instances of stringtoreplace in string with newstring

      Ex: subs(x,a,x\,yz) returns a,yz

      Ex: subs( ,,a b      c   d  e f) returns abcdef

      Ex: subs(\,,,a,b,,,,,,c,,,d,e,f) returns abcdef

 

Case Functions

Random Expression List

R(<value1>,<value2>,...,<valueN>)

      Returns one of the values listed, randomly selected.

 

Example: R(grin,smile,dance)

      Returns either grin, smile or dance, completely by random choice

 

Case Expression

@(<value or variable>,<case1>=<value1>,...,<caseN>=<valueN>)

Takes the <value or variable> and compares it to the cases 1 to N.  If a match occurs, the value associated with that case is returned.  If no match happens, valueN (the last value) is returned.

 

Examples:

@(Death,Good=80,Bruises=40,Death=10)

  returns 10

 

@(@status,Good=80,Bruises=40,Death=10)

  when @status=Good, returns 80

  when @status=Bruises, returns 40

  when @status=Death, returns 10

 

@(@response,10=I'm feeling pretty bad,30=I'm ok,50=I'm great,xxx=No clue)

  when @response=10, returns I'm feeling pretty bad

  when @response=30, returns I'm ok

  when @response=50, returns I'm great

  when @response is anything other than 10, 30 or 50, returns No clue

 

Note: Just like with the string functions, case functions allow you to use the \, character to force a literal comma where you need.

 

Date/Time Functions

datetime(format)

      Returns the current date/time as defined by the format given.  For format is given as a combination of datetime format elements.

 

Basic Date/Time Format Elements

c (or empty)       the full date as defined by your system

d                      day as a number without a leading 0 (1-31)

dd                     day as a number with a leading 0 (01-31)

ddd                   day as an abbreviation (Sun-Sat)

dddd                 day as a full name (Sunday-Saturday)

m                     month as a number without a leading 0 (1-12)

mm                   month as a number with a leading 0 (01-12)

mmm                month as an abbreviation (Jan-Dec)

mmmm             month as a full name (January-December)

yy                     year as a 2-digit number (00-99)

yyyy                 year as a 4-digit number (0000-9999)

h                      hour without a leading 0 (0-23)

hh                     hour with a leading 0 (00-23)

n                      hour without a leading 0 (0-59)

nn                     hour with a leading 0 (00-59)

s                      hour without a leading 0 (0-59)

ss                     hour with a leading 0 (00-59)

t                       the short time format as defined by your system

tt                      the long time format as defined by your system

am/pm              Uses the 12-hour clock for the preceding h or hh specifier, and displays 'am' for any hour before noon, and 'pm' for any hour after noon. The am/pm specifier can use lower, upper, or mixed case, and the result is displayed accordingly

a/p                    Uses the 12-hour clock for the preceding h or hh specifier, and displays 'a' for any hour before noon, and 'p' for any hour after noon. The a/p specifier can use lower, upper, or mixed case, and the result is displayed accordingly

/                       date separator character as defined by your system

:                       time separator character as defined by your system

‘ ‘ or “ “              anything enclosed in quotes is displayed literally

 

For the following example, assume the current date/time as: April 7th 1971 at 10:32:00pm

 

datetime(mm/dd/yy)

      Yields: 04/07/71

datetime(h:nn:ss d/m/yy)

      Yields: 10:32:00 4/7/71

datetime(‘Sometime in ‘mmmm’ after ‘ham/pm)

      Yields: Sometime in April after 10pm

 

The If Command

 

The if command is basically a prefix to any other command you with to execute.  The command can be typed, autotyped, in an event action, an alias command etc.  It differs from a normal command in that you assign a logical condition before it.  For the command to execute, the logical condition must be true.  If the condition is false, and there is also an else command defined, that command will execute, otherwise nothing happens.  Processing the if command is done using the activator character (; is used here as the default).  The format of the If command is described below.

 

;if <Condition> then <Command>

 

OR

 

;if <Condition> then <Command> else <Command2>

 

The “if”  “then” and “else” words are literals and do not change.  <Command> or <Command2> can be, as stated before, any command you would ever want to normally do – entered as you would normally enter it.

 

The <Condition> element, however, must be formatted as this.

 

<Operand1><Logic Control><Operand2>

 

<Operand1> and <Operand2>         Any single variable or value

<Logic Control>                              Logic used to compare the two operands

 

Available Logic Controls

=       Operand1 equals Operand2

>       Operand1 is greater than Operand2

<       Operand1 is less than Operand2

>=     Operand1 is greater than or equal to Operand2

<=     Operand1 is less than or equal to Operand2

<>     Operand1 is not equal to Operand2

 

When comparing two integers, greater than will mean the higher number.  For example, 6 would be “greater than” 1 and 67 would be “less than” 101.

 

When comparing a string to a string, greater than will mean afterwards alphabetically.  For example, cat would be “greater than” apple and fish would be “less than” zebra.

 

When comparing a string to an integer (or vice-versa) the string will be considered 0.

 

Compounding Logic Statements

The condition can either be one logical condition or many different ones compounded together..  You can compound your logic conditions by using the logical functions and(), or() and not().

 

and(condition1,condition2)

·         If both condition1 and condition2 are true, the and function is true

·         If either condition1 or condition2 is false, the and function is false

 

or(condition1,condition2)

·         If either condition1 or condition2 is true, the or function is true

·         If both condition1 and condition2 are false, the or function is false

 

not(condition)

·         If condition is true, the not function is false

·         If condition is false, the not function is true

 

Examples

and(1=1,0=0)                       True because both conditions are true

and(1=0,0=0)                       False because at least one condition is false (the first one)

or(1=0,0=0)                         True because at least one condition is true (the second one)

or(1=0,0=1)                         False because both conditions are false

not(1=1)                              False, because the not() function reverses what would normally be a true statement

or(1=0,not(0=1))                   True because the second condition is true (as a result of the not() function)

and(1=1,or(1=0,0=0))            True because the or() function is true, as is the first condition of the and() function (which envelops the or() function)

or(1=0,and(1=0,0=0))            False because the and() function is false, as is the first condition of the or() function (which envelops the and() function)

not(or(1=0,and(1=0,0=0)))     True - It follows all of the above example’s rules, but the not() function reverses the final result

 

The System Command

 

The system commands allows you to see a local display of variable processing, without sending anything to the server.  All variables and functions will always be evaluated with this command and the result is printed to the display in the system text colors.

 

For example, say you have the variables xxx=50 and yyy=40.  If you then did the command: ;system avg(@xxx,@yyy), the text “System: 45” would be displayed to the screen.  This is basically a handy way to preview variable/function usage before you send anything to the server.

 

Variable Processing Examples

 

My MUD’s HP bar looks like [HP:100/100 SP:120/120].  How can I have, whenever that appears, populate the numbers and neat little gauges on my HP1 and HP2 Bars?

 

1)       Set up an event for [HP:*/* SP:*/*].  In the Select Variable screen, select the following system variables in this order: @HP, @HPMAX, @SP, @SPMAX

 

Now, how hard was that?  You don’t even need any actions defined.  That’s the beauty of system variables.  All the processing for the gauges and whatnot are done at the instant you assign a value to a system variable.

 

My MUD’s HP bar looks like [HP:100/100 SP:120/120 Enemy:<status>].  How can I have Portal©, whenever that appears, populate the numbers and neat little gauges on my HP1 and HP2 Bars?  ALSO, the enemy status ranges from “Good” to “Bleeding” to “Death”  How can I populate those words into numeric values to be used on the neat little enemy gauge?

 

1)   Set up an event for “[HP:*/* SP:*/* Enemy:*]”  In the Select Variable screen, select the following system variables in this order: @HP, @HPMAX, @SP, @SPMAX, @AA

2)       In that event, create the action ;process @ENEMY=@(@AA,Good=100,Bleeding=40,Death=10,else=100)

 

You just used a System-Resident Variable (AA) and the Case Expression function to do that.  Neat huh?

 

Ok, in the above example, I also want the literal enemy status to appear in my HP3 bar - in green if it’s “Good” and yellow if it’s otherwise.

 

You would simply add the following two lines…

 

3)       Create another action ;if @AA=Good then ;process @GLINE1=<g@AA>) else set(@GLINE1=<y@AA>

 

I want to “tell bob hi!” whenever I see ”[Bob logs in]” but I only want to do it once.

 

1)       Declare the variable: sawbob that initializes to 0

2)       Set up an event for “[Bob logs in]”

3)       In that event, create one action for ;if @sawbob=0 then tell bob hi!

4)       Create another action in that event for ;process @sawbob=1

 

I use darts to toss at my enemy, and I get the message “You have 10 darts left” after I use one of them (10 as an example).  I want to be alerted visually and by sound as to when my dart inventory hits 10.

 

1)       Declare the variable: darts that initializes to 0

2)       Set up an event for “You have * darts left”

3)       In that event, create one action for ;if darts=10 then ;5 say I only have 10 darts!

4)       Create another action in that event for ;if darts=10 then ;process @SOUND=beep

 

This is assuming you have “beep.wav” in your …Portal\media\sounds directory.

 

Appendix: Coloring the GLine1 & GLine2

The glines appear on the HP3 Bar.  The text that appears has a black background and the font is colored white by default.  While you cannot change the black background, you can change the font color when setting it.

 

All you have to do is encapsulate the text you desire to color in the format specified below.  You can't use < or > anywhere in the glines as normal text or it'll screw up.  If you already use < or > enclosures, you'll have to use something else to encapsulate your data.  All text not enclosed in any color activators appear as white.

 

Format: <x><word>

<x>         color code

<word>    text to be colored (any length)

 

Valid Color Codes

y       yellow

r        red

b       blue

g       green (windows calls it lime)

c       cyan (windows calls it aqua)

v        violet (windows calls it fuchsia)

s       silver (dim white)

 

Example 1:     The red <rfox> jumped over the cyan <cdog>

Display:         The red fox jumped over the cyan dog

            ("fox" will appear in red, "dog" will appear in cyan)

 

Example 2:     Spells Activated: [<bshield>,<gmagic missile>]

Display:         Spells Activated: [shield,magic missile]

            ("shield" will appear in blue, "magic missile" will appear in green)

 

Example 3:     Demon Follower's Health: <a95%>

Display:         Demon Follower's Health: 95%

            (The whole line appears in white)

 

Now, why would the 95% appear all in white?  Because "a" was used, which is not a valid code.

 

We suggest you keep the number of uses of the activator to under 10 per gline.  That means under 10 uses of the <> pairings.